feat(storybook): expose component docs to agents via official MCP addon (#3527) - #3736

I reviewed this head and found blocking issues.

[P2] MCP addon docs-only claim is not a server boundary and the endpoint is exposed on LAN

@storybook/addon-mcp replaces options via X-MCP-Toolsets (main.ts:45). The live tools/list with a dev header changes from 3 docs tools to 4 dev tools. The storybook script does not bind to loopback, so *:6006 is reachable from 10.7.0.13:6006 without auth — an on-LAN caller can re-enable the dev toolset and obtain a filesystem existence oracle (/etc/passwd vs pathNotFound).

Fix: bind to loopback (and --exact-port) and intersect request-selected toolsets with the configured allowlist; cover with header-injection tests.

[P2] Root .mcp.json is not discovered by Codex

AGENTS.md claims the endpoint is registered, but Codex discovers via .codex/config.toml [mcp_servers], not the Claude-style root JSON. Result: Codex sees the mandatory query instruction but has no tools.

Fix: ship a real project config for each claimed client or narrow the claim; verify via actual client discovery.

Checks on d75281cb67 are test: failure (unrelated CLI EOF backoff flake, but still red — not green). Code issues are independent of CI.

Adds @storybook/addon-mcp to apps/desktop/.storybook/main.ts so an agent can query component docs over MCP instead of reading source, wires .mcp.json, pins the dev server with --exact-port, and adds a root AGENTS.md.

The plumbing is clean and I want to credit that before the findings. The addon goes into apps/desktop devDependencies, lock-pinned, and I confirmed it stays out of the shipped closure: third-party-closure.mjs:98-129 defines that closure as the prod closure plus maka.rendererBundledDependencies, and the addon is in neither, so audit-shipped-dependencies.mjs and the generated THIRD_PARTY_NOTICES are unaffected and there is no NOTICE obligation. The twelve transitive packages are MIT except one ISC, all ASF Category A. There is no CI install gap either — every isStorybookPath trigger in ci-test-plan.mjs:398-415 also sets code = true, which is what gates npm ci. Telemetry is a non-issue: the addon gates on core.disableTelemetry, which main.ts already sets.

The problem is not the plumbing. It is what this installs as an authority.

P1 — the root AGENTS.md is a tracked file at a path this project deliberately keeps untracked, and it is injected into Maka's own system prompt.

Two separate reasons this cannot land as part of this PR.

First, AGENTS.md is not tracked on main, and maintainer checkouts keep a local one via .git/info/exclude. Committing a tracked root AGENTS.md will make git pull refuse in every checkout that has a local file at that path. That is not a style objection; it breaks the working tree of anyone set up the current way.

Second, and more important: WORKSPACE_INSTRUCTION_FILES in packages/runtime/src/system-prompt/workspace-instructions.ts:40 is ['AGENTS.md', 'CLAUDE.md', 'GEMINI.md']. Maka injects the project's AGENTS.md into the system prompt. So this file is not documentation — it is behavior, for every agent run inside this repository. And what it says is "Prefer composing existing packages/ui components. Introduce a new component only when nothing existing fits", with no mention of Astryx at all. Our actual authority is DESIGN.md:186, "Use Astryx primitives as the default seam", backed by the CI-gated surface inventory. An agent that reads only the injected instruction will build a new packages/ui component where DESIGN.md requires an Astryx primitive, and the surface-inventory gate will grade the result.

Please split the AGENTS.md out of this PR. If you want project instructions for agents, that is a worthwhile change but it is its own decision, it has to reconcile with DESIGN.md rather than restate it more weakly, and it needs the untracked-file collision resolved first.

P2 — the addon injects vendor-authored instructions that claim exclusive authority over component APIs, and our catalog cannot back that claim.

@storybook/addon-mcp's preset puts STORYBOOK_MCP_INSTRUCTIONS into the MCP server's instructions field, which clients inject into the system prompt. That text says to answer questions about component props and usage from the documentation tools and never from source or type definitions, and that if something is not documented, it does not exist.

Against our tree that instruction is actively wrong. Only 5 of 32 story files declare meta.component, there is no autodocs tag anywhere, and @astryxdesign/core — the primitive layer DESIGN.md makes the default seam — has no stories at all. So: an agent needs a busy button. DESIGN.md:229 requires the Astryx isLoading prop, "always — no hand-swapped labels, icons, or disable-plus-spinner recreations". The manifest has no such component, the injected instruction says the prop does not exist, and the agent hand-rolls a disable-plus-spinner. That is precisely the drift DESIGN.md exists to prevent, now instructed.

Unlike the AGENTS.md above, this string is vendor-controlled and can change on any npm update inside ^0.7.0, so it cannot be reviewed per change. If we want this addon, the honest sequencing is to get meta.component and autodocs coverage up — and Astryx covered at all — before an instruction that says "if it is not documented, it does not exist" is true enough to inject.

Three P3s:

• The main.ts comment says the security boundary is the dev server's loopback binding. It is not. The addon's X-MCP-Toolsets: dev header overrides the configured toolsets per request against registrations that are toolset-blind, and what actually blocks a malicious page today is that the transport is constructed with no cors option, so no Access-Control-Allow-Origin is emitted. The addon never validates Origin. Consequence is bounded — I found no fs writes in the bundle; the dev toolset's worst reach is execSync('git status --porcelain') and story-source reads the Vite dev server already serves on that port. One thing I could not verify: whether Storybook's own host check runs before the addon's /mcp route. If it does not, DNS rebinding lands same-origin and the CORS absence buys nothing. Worth checking with curl -X POST -H 'Host: evil.example' -H 'Origin: https://evil.example' -H 'X-MCP-Toolsets: dev' http://127.0.0.1:6006/mcp before merge. Please fix the comment either way — a wrong stated boundary is worse than none.
• --exact-port turns a port collision into process.exit(-1) instead of falling forward to 6007. This project's workflow encourages multiple worktrees, and apps/desktop/tests/smoke.md:71 documents that command. A deliberate trade for the hardcoded .mcp.json URL, but say so.
• .mcp.json is unclassified by ci-test-plan.mjs, so it falls through to unknownCode = true and forces a full run. Any future .mcp.json-only PR runs the entire suite for nothing.

Ungraded notes: the body answers "does this PR entail a change in behavior?" with No, but the addon unconditionally sets features.componentsManifest: true and Storybook applies that to builds, so CI's build-storybook now generates component manifests — and the body does not claim build-storybook was run locally. "Exposes exactly the three docs tools" holds only for the default request path; the header override is disclosed in the main.ts comment but not in the summary. Separately, .gitattributes:8-11 export-ignores /.claude as repository-local agent configuration; .mcp.json is the same category and is not export-ignored, so it would ship in the ASF source artifact — my call to make, flagging it. Finally, npm run lint is Biome only while CI runs npx knip --workspace apps/desktop separately; the addon publishes no "." export and knip's storybook plugin routes addon names through deferred resolution. I could not verify whether that resolves cleanly — please confirm the knip step passes.

Root cause: right seam, wrong authority. Extending the existing Storybook config instead of building a parallel harness is the correct instinct. But what gets installed is a second, vendor-authored source of truth about component APIs, in a repository whose authority is DESIGN.md plus Astryx primitives plus the generated surface inventory — and then a root AGENTS.md restates that authority a third time, more weakly and without Astryx. One fact, three representations, one of them written by a third party and shipped inside a caret range.

AI use: Claude Code (Opus) produced the initial findings, including unpacking @storybook/addon-mcp@0.7.0 and its transitive tree to read the actual bundles and license set. I independently re-verified the P1 — that AGENTS.md is absent from origin/main, excluded via .git/info/exclude, and listed in WORKSPACE_INSTRUCTION_FILES — and the DESIGN.md authority lines it conflicts with. The DNS-rebinding ordering question is explicitly unverified. The reviewer of record reviewed and accepted this.